	<div id="preamble">
	  
	  <table class="module">
	      <tr><th>Description:</th><td>Full-featured reverse-proxying and/or stand-alone load balancer</td></tr>
  <tr><th>Status:</th><td>Extension</td></tr>
  <tr><th>Module Identifier:</th><td>athena_module</td></tr>
  <tr><th>Source File:</th><td>mod_athena.c (plus others)</td></tr>
  <tr><th>Compatibility:</th><td>v 1.x Requires httpd-2.0.43 or newer</td></tr>
  <tr><th>Compatibility:</th><td>v 2.x Requires httpd-2.2.0 or newer</td></tr>
</table>

	  <h3>Summary</h3>
	  <p>This module is designed to allow httpd to act as a load balancer,
	    either internally to apache's own mod_proxy (for reverse proxying), or 
	    externally to machines querying it. Arbitrary statistics are sent
	    to the engine via a simple GET plus query-string interface, 
            from which it will then make decisions based on chosen
	    algorithms. You are able to manage farms of servers, mark them in 
      different states, and forward disabled or down systems or farms to new targets, 
      among other administrative features. In version 2.x (requires httpd-2.2.x),
      you can manipulate loadbalancing decisions with your back-end application by
      setting a secret key secured cookie that the load balancer will intercept and
      use to modify the algorithm. This feature allows you to maintain stick sessions
      to a specific server, or prioritize farms using business rules (QoS).
    </p>
          <p>If you are using commercial hardware or software
            to load balance protocols that can be handled by apache's mod_proxy,
            then you should be able to use this as a drop in replacement.
          </p>

	  <p>In the reverse http(s) proxy configuration, a request from a client is answered by
	    apache. The request is handled by mod_proxy, which would then rewrite
	    the url to substitute a mod_athena "AthFarm" where the target hostname
      usually resides.
	  <blockquote><code>httpd.conf: ProxyPass &nbsp;&nbsp;&nbsp; 
    /reports/ &nbsp;&nbsp;&nbsp; http://farm_one/reports/</code></blockquote>
  Then, mod_athena takes over the request. It will look up the farm,
  run the  algorithm and analyze health status for that farm, 
      and then substitute a real address for
  for the farm name. If the farm or servers are disabled or all are sick, a complete 
      alternative URL will be substitued.
      The result is handed back to mod_proxy to finish the request.
  <blockquote><code>pseudo-code: http://farm_one/reports/ 
      --> http://chosen_server/reports/</code></blockquote>
  <blockquote><code>pseudo-code: http://farm_one/reports/ 
      --> http://www.yoursite.com/outage/</code></blockquote>
</p>
  <p>In the query configuration, a client (in this case probably another
    application) sends a GET request with a query string containing the
    desired farm(s) to httpd. 
    <blockquote><code>&gt; fetch -q -o - http://my_athena/ath/balance/?farm_one<br>
	chosen_server</code></blockquote>
    The module engine will catch this request,
    run the appropriate algorithm(s), and return the appropriate result(s)
    as text content to the client.</p>
  <p>You can easily use mod_athena in both modes in the same instance of the engine.</p>

<p>The package comes with scripts that can be used to mirror and monitor the system, along 
with a perl package that provides an HTML based front end for runtime management.
</p>

</div>

